React useFormStatus: Sveobuhvatan vodič za upravljanje stanjem obrazaca

useFormStatus hook, predstavljen u Reactu 18, pruža moćan i učinkovit način za upravljanje stanjem slanja obrazaca unutar React Server Components. Ovaj hook je posebno dizajniran za rad sa serverskim akcijama, nudeći besprijekornu integraciju za obradu slanja obrazaca izravno na poslužitelju. Pojednostavljuje proces praćenja statusa slanja obrasca, pružajući vrijedne informacije poput toga je li slanje u tijeku, je li uspjelo ili je došlo do pogreške. Ovaj vodič istražuje mogućnosti useFormStatus hooka, njegove prednosti i praktične primjere koji demonstriraju njegovu upotrebu u različitim scenarijima.

Razumijevanje serverskih akcija i useFormStatus

Prije nego što zaronimo u useFormStatus, ključno je razumjeti React Server Components i Server Actions (serverske akcije). Serverske akcije omogućuju vam definiranje funkcija koje se izvršavaju na poslužitelju, a izravno su dostupne iz vaših React komponenti. To omogućuje obradu slanja obrazaca, dohvaćanje podataka i druge operacije na strani poslužitelja bez potrebe za zasebnim API endpointom.

useFormStatus hook zatim pruža uvid u izvršavanje ovih serverskih akcija koje su pokrenute slanjem obrasca.

Što je useFormStatus?

useFormStatus je React hook koji vraća objekt s informacijama o statusu posljednjeg slanja obrasca. Te informacije uključuju:

• pending: Booleova vrijednost koja označava je li slanje obrasca trenutno u tijeku.
• data: Objekt FormData povezan sa slanjem.
• method: HTTP metoda korištena za slanje (obično 'POST').
• action: Funkcija serverske akcije koja je pokrenuta.

Prednosti korištenja useFormStatus

Korištenje useFormStatus nudi nekoliko ključnih prednosti:

• Pojednostavljeno upravljanje stanjem: Uklanja potrebu za ručnim upravljanjem stanjem kako bi se pratio status slanja obrasca. Hook se automatski ažurira kako slanje napreduje.
• Poboljšano korisničko iskustvo: Pruža povratne informacije korisnicima u stvarnom vremenu, poput prikaza indikatora učitavanja dok se obrazac obrađuje ili prikazivanja poruka o pogrešci u slučaju neuspjeha.
• Čist kod: Potiče deklarativniji i održiviji kod odvajanjem logike slanja obrasca od renderiranja komponente.
• Besprijekorna integracija sa serverskim akcijama: Dizajniran da savršeno radi sa serverskim akcijama, olakšavajući obradu slanja obrazaca izravno na poslužitelju.

Praktični primjeri korištenja useFormStatus

Istražimo nekoliko praktičnih primjera kako bismo ilustrirali upotrebu useFormStatus u različitim scenarijima.

Osnovno slanje obrasca s indikatorom učitavanja

Ovaj primjer prikazuje jednostavan obrazac s indikatorom učitavanja koji se prikazuje dok se obrazac šalje.

Serverska akcija (actions.js):

'use server'

export async function submitForm(formData) {
  // Simulacija kašnjenja kako bi se demonstriralo stanje učitavanja
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');
  console.log('Obrazac poslan s imenom:', name);
  return { message: `Obrazac je uspješno poslan s imenom: ${name}` };
}

React komponenta (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'

function FormComponent() {
  const { pending } = useFormStatus()

  return (
    

      Ime:
      
      
        {pending ? 'Šalje se...' : 'Pošalji'}
      
    
  )
}

export default FormComponent

U ovom primjeru, svojstvo pending iz useFormStatus koristi se za onemogućavanje polja za unos i gumba dok se obrazac šalje te za prikaz poruke "Šalje se...".

Obrada stanja uspjeha i pogreške

Ovaj primjer prikazuje kako obraditi stanja uspjeha i pogreške nakon slanja obrasca.

Serverska akcija (actions.js):

'use server'

export async function submitForm(formData) {
  // Simulacija kašnjenja
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');

  if (!name) {
    throw new Error('Ime je obavezno');
  }

  console.log('Obrazac poslan s imenom:', name);
  return { message: `Obrazac je uspješno poslan s imenom: ${name}` };
}

React komponenta (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await submitForm(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      Ime:
      
      
        {pending ? 'Šalje se...' : 'Pošalji'}
      
      {pending && 
Šalje se...
}
      {message && 
{message}
}
      {error && 
Pogreška: {error}
}
    
  )
}

export default FormComponent

U ovom primjeru, try/catch blok se koristi u funkciji handleSubmit. Ako serverska akcija baci pogrešku, ona se hvata i prikazuje korisniku. Poruka o uspjehu prikazuje se nakon uspješnog slanja.

Korištenje FormData za složene podatke

useFormStatus radi besprijekorno s FormData, omogućujući vam lako rukovanje složenim strukturama podataka. Evo primjera koji prikazuje kako učitati datoteke.

Serverska akcija (actions.js):

'use server'

export async function uploadFile(formData) {
  // Simulacija obrade datoteke
  await new Promise(resolve => setTimeout(resolve, 2000));

  const file = formData.get('file');

  if (!file) {
    throw new Error('Nije učitana datoteka');
  }

  console.log('Datoteka učitana:', file.name);
  return { message: `Datoteka uspješno učitana: ${file.name}` };
}

React komponenta (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { uploadFile } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await uploadFile(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      Učitaj datoteku:
      
      
        {pending ? 'Učitavanje...' : 'Učitaj'}
      
      {pending && 
Učitavanje...
}
      {message && 
{message}
}
      {error && 
Pogreška: {error}
}
    
  )
}

export default FormComponent

Ovaj primjer prikazuje kako rukovati učitavanjem datoteka pomoću FormData. Serverska akcija dohvaća datoteku iz FormData objekta i obrađuje je. useFormStatus hook upravlja stanjem učitavanja dok se datoteka prenosi.

Najbolje prakse za korištenje useFormStatus

Kako biste maksimalno iskoristili prednosti useFormStatus, razmotrite sljedeće najbolje prakse:

• Pružite jasne povratne informacije korisniku: Koristite stanje pending za prikaz informativnih indikatora učitavanja i onemogućite elemente obrasca kako biste spriječili višestruka slanja.
• Elegantno rukujte pogreškama: Implementirajte obradu pogrešaka kako biste uhvatili iznimke u vašim serverskim akcijama i prikazali korisnički prijateljske poruke o pogreškama.
• Validirajte podatke na poslužitelju: Provedite validaciju na strani poslužitelja kako biste osigurali integritet i sigurnost podataka.
• Neka serverske akcije budu sažete: Usredotočite serverske akcije na specifične zadatke kako biste poboljšali performanse i održivost.
• Uzmite u obzir pristupačnost: Osigurajte da su vaši obrasci pristupačni pružanjem odgovarajućih oznaka, ARIA atributa i podrške za navigaciju tipkovnicom.

Napredni slučajevi upotrebe

Osim osnovnih primjera, useFormStatus se može koristiti u složenijim scenarijima:

• Progresivno poboljšanje: Koristite serverske akcije i useFormStatus za progresivno poboljšanje vaših obrazaca, pružajući osnovno iskustvo korisnicima s onemogućenim JavaScriptom i bogatije iskustvo onima s omogućenim.
• Optimistična ažuriranja: Implementirajte optimistična ažuriranja tako da ažurirate korisničko sučelje odmah nakon slanja obrasca, pod pretpostavkom da će slanje uspjeti. Vratite ažuriranje ako slanje ne uspije.
• Integracija s bibliotekama za obrasce: Integrirajte useFormStatus s popularnim bibliotekama za obrasce poput Formika ili React Hook Form za upravljanje stanjem i validacijom obrasca. Iako te biblioteke često imaju vlastito upravljanje stanjem, useFormStatus može biti koristan za završnu fazu slanja serverskoj akciji.

Razmatranja za internacionalizaciju (i18n)

Prilikom izrade obrazaca za globalnu publiku, internacionalizacija (i18n) je ključna. Evo kako uzeti u obzir i18n pri korištenju useFormStatus:

• Lokalizirane poruke o pogreškama: Osigurajte da su poruke o pogreškama prikazane korisniku lokalizirane na njihov željeni jezik. To se može postići pohranjivanjem poruka o pogreškama u datoteke s prijevodima i korištenjem biblioteke poput react-intl ili i18next za dohvaćanje odgovarajućeg prijevoda.
• Formatiranje datuma i brojeva: Rukujte formatiranjem datuma i brojeva u skladu s lokalnim postavkama korisnika. Koristite biblioteke poput Intl.DateTimeFormat i Intl.NumberFormat za ispravno formatiranje ovih vrijednosti.
• Podrška za pisanje s desna na lijevo (RTL): Ako vaša aplikacija podržava jezike koji se pišu s desna na lijevo (npr. arapski, hebrejski), osigurajte da su vaši obrasci pravilno stilizirani kako bi se prilagodili RTL rasporedima.
• Validacija obrazaca: Prilagodite pravila validacije obrazaca različitim lokalnim postavkama. Na primjer, validacija telefonskog broja može se značajno razlikovati među državama.

Primjer lokaliziranih poruka o pogreškama:

// prijevodi/hr.json
{
  "form.error.nameRequired": "Molimo unesite svoje ime.",
  "form.success.submission": "Hvala na vašem slanju!"
}

// prijevodi/fr.json
{
  "form.error.nameRequired": "Veuillez entrer votre nom.",
  "form.success.submission": "Merci pour votre soumission !"
}

// Komponenta koja koristi react-intl
import { useIntl } from 'react-intl';

function FormComponent() {
  const intl = useIntl();
  const [error, setError] = useState(null);

  // ...

  catch (e) {
    setError(intl.formatMessage({ id: 'form.error.nameRequired' }));
  }
}

Razmatranja o pristupačnosti

Pristupačnost je ključni aspekt izgradnje inkluzivnih web aplikacija. Evo nekoliko razmatranja o pristupačnosti koja treba imati na umu pri korištenju useFormStatus:

• ARIA atributi: Koristite ARIA atribute kako biste pomoćnim tehnologijama pružili informacije o statusu obrasca. Na primjer, koristite aria-busy="true" na gumbu za slanje dok je obrazac u stanju čekanja.
• Oznake: Osigurajte da sva polja obrasca imaju jasne i opisne oznake koje su povezane s elementima za unos pomoću elementa <label>.
• Poruke o pogreškama: Prikazujte poruke o pogreškama na način koji je lako uočljiv i razumljiv korisnicima s invaliditetom. Koristite ARIA atribute poput aria-live="assertive" za najavu poruka o pogreškama čitačima zaslona.
• Navigacija tipkovnicom: Osigurajte da korisnici mogu navigirati obrascem koristeći samo tipkovnicu. Koristite tabindex atribut za kontrolu redoslijeda u kojem elementi dobivaju fokus.
• Kontrast boja: Osigurajte da boje teksta i pozadine korištene u obrascu imaju dovoljan kontrast kako bi bile lako čitljive korisnicima s oštećenjem vida.

useFormStatus u usporedbi s tradicionalnim upravljanjem stanjem

Tradicionalno, React programeri su upravljali stanjem slanja obrazaca koristeći stanje komponente (useState) ili složenije biblioteke za upravljanje stanjem (npr. Redux, Zustand). Evo usporedbe tih pristupa s useFormStatus:

Značajka	useFormStatus	useState	Eksterno upravljanje stanjem
Složenost	Niska	Srednja	Visoka
Integracija sa serverskim akcijama	Besprijekorna	Zahtijeva ručnu integraciju	Zahtijeva ručnu integraciju
Ponavljajući kod (Boilerplate)	Minimalan	Umjeren	Značajan
Prikladni slučajevi upotrebe	Obrasci koji se šalju izravno serverskim akcijama	Jednostavni obrasci s ograničenim stanjem	Složeni obrasci s dijeljenim stanjem među komponentama

useFormStatus se ističe kada vaši obrasci izravno komuniciraju s React Server Actions. Smanjuje ponavljajući kod i pojednostavljuje proces. Međutim, za vrlo složene obrasce s stanjem koje se dijeli među više komponenti, potpuna biblioteka za upravljanje stanjem i dalje može biti opravdana.

Rješavanje uobičajenih problema

Evo nekih uobičajenih problema s kojima se možete susresti pri korištenju useFormStatus i kako ih riješiti:

• useFormStatus se ne ažurira:
  • Provjerite koristite li useFormStatus unutar <form> elementa čiji je action prop postavljen na serversku akciju.
  • Provjerite je li serverska akcija ispravno definirana i izvezena.
  • Provjerite postoje li pogreške u serverskoj akciji koje bi mogle spriječiti njezino uspješno dovršavanje.
• Poruke o pogreškama se ne prikazuju:
  • Provjerite hvatate li ispravno pogreške u svojoj serverskoj akciji i vraćate li poruku o pogrešci.
  • Provjerite prikazujete li poruku o pogrešci u svojoj komponenti koristeći stanje error.
• Indikator učitavanja se ne pojavljuje:
  • Provjerite koristite li stanje pending iz useFormStatus za uvjetni prikaz indikatora učitavanja.
  • Provjerite da li serverskoj akciji zaista treba neko vrijeme da se dovrši (npr. simuliranjem kašnjenja).

Zaključak

useFormStatus pruža čist i učinkovit način za upravljanje stanjem slanja obrazaca u React aplikacijama koje koriste Server Components. Korištenjem ovog hooka možete pojednostaviti svoj kod, poboljšati korisničko iskustvo i besprijekorno se integrirati sa serverskim akcijama. Ovaj vodič je pokrio osnove useFormStatus hooka, pružio praktične primjere i raspravio najbolje prakse za njegovu učinkovitu upotrebu. Uključivanjem useFormStatus u vaše React projekte, možete optimizirati rukovanje obrascima i izgraditi robusnije i korisnički prijateljskije aplikacije za globalnu publiku.